home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.101 < prev    next >
Encoding:
Text File  |  1991-06-28  |  5.0 KB  |  114 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #101:        Patching the Toolbox
  9.  
  10. Written by:  Dave Lyons                                              May 1991
  11.  
  12. This Technical Note presents guidelines on when and how to patch Apple IIgs 
  13. Toolbox functions.
  14. _____________________________________________________________________________
  15.  
  16.  
  17. Introduction
  18.  
  19. There is normally no need to patch the toolbox; avoid patching whenever you 
  20. can.  If you must patch a toolbox function, be sure to have a good 
  21. understanding of the call you're patching and how it interacts with the whole 
  22. system.
  23.  
  24. No toolbox patch is risk-free.  Future version of the toolboxs could change 
  25. in ways that make your patch less useful.  (For example, if you patched 
  26. NewControl to have some global effect on controls being created, your patch 
  27. became less useful when NewControl2 was introduced in System Software 5.0.)
  28.  
  29. For better compatibility, patch with care!  If any parameters passed are 
  30. outside the range that was allowed when you wrote your patch, just pass the 
  31. call straight through; the new toolbox probably knows something your patch 
  32. doesn't.
  33.  
  34.  
  35. Patching the Toolbox From an Application
  36.  
  37. An application can easily patch a function for the duration of that 
  38. application.
  39.  
  40. After starting up the tools, construct a Function Pointer Table (FPT) the 
  41. same size as the existing FPT (call GetTSPtr and examine the first word of 
  42. the table; multiply it by four to get the size of the FPT in bytes).  The 
  43. first longword of your FPT is the number of functions in the tool set; do not 
  44. hard-code this value!  Get it from the existing FPT on the fly.  Fill the 
  45. rest of your FPT with zeroes, except for the functions you want to patch.  
  46. You must always patch the BootInit function (the first function) to return no 
  47. error.  Remember that the function pointer values are one less than the 
  48. addresses of your replacement functions.
  49.  
  50. On exit, when you call TLShutDown your patch will be automatically removed.  
  51. (If you're using ShutDownTools, you should call MMShutDown and TLShutDown 
  52. after you call ShutDownTools.)
  53.  
  54. Note:  In the description of SetTSPtr on page 24-19 of Apple IIgs Toolbox 
  55.        Reference, Volume 2, there are several references to the TPT.  Keep in 
  56.        mind that the TPT is the Toolset Pointer Table, not the Function Table 
  57.        Pointer you pass to SetTSPtr.  While SetTSPtr copies the TPT to RAM if 
  58.        necessary, it does not make a copy of the FPT.  After you call 
  59.        SetTSPtr, the FPT you passed is being used, and any zero values in 
  60.        your table were filled in.
  61.  
  62.  
  63. Patching the Toolbox From a Desk Accessory or Setup File
  64.  
  65. A permanent initialization file or Desk Accessory can patch toolbox functions 
  66. at boot time by using constructing an FPT for SetTSPtr, as described for an 
  67. application, but there is an extra step to make the patch "stick."
  68.  
  69. Call LoadOneTool and then SetTSPtr; then call SetDefaultTPT (see Apple IIgs 
  70. Toolbox Reference Volume 3, page 51-16).
  71.  
  72. It is not safe to call SetDefaultTPT while an application is running 
  73. (temporary application patches would be made permanent, and later the 
  74. application would go away).  Since there are desk accessories that install 
  75. other desk accessories while applications are running, desk accessory that 
  76. wants to install a tool patch should make the class-one GS/OS GetName call; 
  77. if the null string is returned, no application is executing yet, so it is 
  78. safe to make the patch.  (Otherwise the desk accessory should ask the user to 
  79. put the desk accessory file in the System:Desk.Accs folder and restart the 
  80. system.)
  81.  
  82.  
  83. Avoid Tail Patching
  84.  
  85. The best kind of patch is a pre-patch or head patch:  it does some extra work 
  86. and then jumps to the original function (as found in the FPT before applying 
  87. the patch).  Make sure the A, X, and Y registers contain the same values when 
  88. you jump to the original function as they did when the patch got control.
  89.  
  90. A "tail patch" which calls the original function and then regains control is 
  91. much more of a compatibility risk, because there are several instances where 
  92. System Software patches examine return addresses to fix problems in large 
  93. toolbox calls which call small ones (by patching the small one to realize 
  94. it's being called from the big one, many K of RAM remain available to your 
  95. application).
  96.  
  97. If you tail patch a function which the system already patched, you may 
  98. prevent the toolbox from working correctly.
  99.  
  100.  
  101. Patching the Tool Dispatcher
  102.  
  103. If you need to patch a large number of functions, especially for a general 
  104. purpose utility like a debugger, it may make more sense to patch the tool 
  105. dispatcher vectors instead of patching individual functions.  See Apple IIgs 
  106. Technical Note #87, Patching the Tool Dispatcher.
  107.  
  108.  
  109. Further Reference
  110. _____________________________________________________________________________
  111.   o  Apple IIgs Toolbox Reference
  112.   o  Apple IIgs Technical Note #87, Patching the Tool Dispatcher
  113.  
  114.